🟠 Major · useImperativeHandle recreates the handle before nativeRef is set, leaving ref.current null forever

On first mount, the useImperativeHandle factory runs before nativeRef.current is assigned (layout effects run before host refs are committed), returning null. Since the deps are [setCurrent] and setCurrent is stable, the factory never re-runs, so ref.current stays null for the pager's lifetime and every ref.current?.setPage(n) silently no-ops.

Suggested change

Make the imperative handle re-run once the native instance exists (e.g. store nativeRef in state via a ref callback and add that to the deps), and verify with a caller that calls setPage inside its own mount effect.

  useImperativeHandle<PagerViewRef | null, PagerViewRef | null>(
    ref,
    () => {
      const instance = nativeRef.current;
      if (!instance) {
        return null;
      }
      return Object.assign(instance, {
        setPage: (selectedPage: number) => {
          setCurrent?.(selectedPage);
          bindCommand(nativeRef, PagerViewNativeCommands.setPage)(selectedPage);
        },
        setPageWithoutAnimation: (selectedPage: number) => {
          setCurrent?.(selectedPage);
          bindCommand(
            nativeRef,
            PagerViewNativeCommands.setPageWithoutAnimation
          )(selectedPage);
        },
        setScrollEnabled: bindCommand(
          nativeRef,
          PagerViewNativeCommands.setScrollEnabledImperatively
        ),
        pagerView: instance,
      });
    },
    [setCurrent, instanceReady]
  );

Reply @apex-sentinel-staging note ... to add context, or @apex-sentinel-staging pivot ... if this is wrong — I will re-check the cited code.

Useful? Reply @apex-sentinel-staging like, or @apex-sentinel-staging dislike <why> if it is not.

No longer raised on b0040e6.

🆕 🟡 Minor · Stale pages leak into mountedKeys, and pageKey can alias two different pages, so a newly added page renders another page's already-mounted content

mountNear (useLazyPages.tsx:30-38) only ever unions into the set; nothing ever prunes keys that are no longer in pages. Combined with pageKey collapsing everything to a string (useLazyPages.tsx:12-13), pages.map (line 50) matches a different child element against a key left over from an earlier child. Concretely, with keyless children Children.toArray assigns positional keys .0, .1, …, so removing the first page of [A,B,C] re-keys the list to [.0=B, .1=C] and B renders immediately because .0 is still marked mounted from A — the two elements share one identity string while React sees two different elements. The README ("Pages are tracked by key, so adding or removing pages doesn't remount the others", README.md:131) states the guarantee without the precondition that keys be unique and stable, and pages whose keys are positional (the usePagerView pages array, src/usePagerView.ts:49-62, which removePage shrinks from the end) is exactly the shape where the invariant silently holds or silently breaks depending on which end pages are removed from. The unbounded set itself is a small leak of string keys that never shrink as pages churn.

Suggested change

Note in the README Lazy pages section that children need unique, stable keys for the "adding or removing pages doesn't remount the others" guarantee, and prune mountedKeys against the current pages keys so removed pages do not pin their keys.

Reply @apex-sentinel-staging note ... to add context, or @apex-sentinel-staging pivot ... if this is wrong — I will re-check the cited code.

Useful? Reply @apex-sentinel-staging like, or @apex-sentinel-staging dislike <why> if it is not.

No longer raised on b0040e6.

🆕 🟡 Minor · mountedKeys only ever grows: keys of removed pages are retained for the pager's lifetime

mountNear builds next as a union of mounted and the nearby keys (useLazyPages.tsx:30-38) and nothing ever removes a key. onSelect/setCurrent move current, but a key whose page has left children (e.g. usePagerView's removePage, or any list that shrinks) stays in mountedKeys forever. The set is also ReadonlySet<string> state, so every mount event allocates a fresh Set copy. For a pager with a dynamically shrinking page list this is unbounded retention keyed on stale element keys, and it makes the documented promise "Pages are tracked by key, so adding or removing pages doesn't remount the others" (README.md:132) only half true: re-adding a page whose key is still in the set mounts it immediately with no placeholder, while a freshly added page gets one — the two directions are asymmetric for reasons a caller cannot see from the docs.

Suggested change

Prune keys that are no longer present in children when computing the next mounted set (or intersect with the current page keys), and note the mount-on-re-add behaviour in the Lazy pages docs section.

Reply @apex-sentinel-staging note ... to add context, or @apex-sentinel-staging pivot ... if this is wrong — I will re-check the cited code.

Useful? Reply @apex-sentinel-staging like, or @apex-sentinel-staging dislike <why> if it is not.

No longer raised on b0040e6.

🆕 🔵 Nit · pageKey folds every keyless child into the single key "undefined"

Children.toArray guarantees keys only for valid elements; a raw string/number child (which <PagerView>child</PagerView> accepts as children) yields pageKey === 'undefined', so all such pages share one entry in mountedKeys and mount/unmount together. Pages are documented as needing a key (README "Pages are tracked by key"), so this is reachable only by misuse — falling back to the index, e.g. ?? String(index), would make the degenerate case behave per-page instead of as one shared page.

Suggested change

Fall back to the page index in pageKey so a child without a key is still tracked as its own page.

Reply @apex-sentinel-staging note ... to add context, or @apex-sentinel-staging pivot ... if this is wrong — I will re-check the cited code.

Useful? Reply @apex-sentinel-staging like, or @apex-sentinel-staging dislike <why> if it is not.

No longer raised on b0040e6.

🆕 🔵 Nit · lazyPreloadDistance beyond the native offscreenPageLimit unmounts a page the native pager is currently showing

useLazyPages.tsx:27 derives distance purely from preloadDistance, and PagerView passes the children prop straight through to the native component, so a page that leaves the mounted window is replaced in place by <View>{renderPlaceholder?.(index)}</View> (useLazyPages.tsx:49-55) — the child's content is swapped while the native pager may still be compositing it. Android's offscreenPageLimit defaults to 1 (src/PagerViewNativeComponent.ts:26 has no explicit default documented here, README.md:109 says "Defaults to 1", and the README's own Lazy section at 154 stresses it is "unrelated" to lazy). So <PagerView lazy lazyPreloadDistance={0} offscreenPageLimit={1}> — a configuration the README never warns against, and the lazy example does not use — unmounts the neighbour page that the pager keeps composed for the transition: the user dragging one page sees real content on one side and a placeholder on the other, then the content pops in on settle. Nothing in useLazyPages or PagerView ties distance to offscreenPageLimit or takes the max of the two.

Suggested change

Take the effective distance as max(lazyPreloadDistance, offscreenPageLimit ?? 1) in PagerView before calling useLazyPages, or document that lazyPreloadDistance must be >= offscreenPageLimit on Android.

Reply @apex-sentinel-staging note ... to add context, or @apex-sentinel-staging pivot ... if this is wrong — I will re-check the cited code.

Useful? Reply @apex-sentinel-staging like, or @apex-sentinel-staging dislike <why> if it is not.

No longer raised on b0040e6.

🆕 🔵 Nit · lazyPreloadDistance is clamped for the effective window but the example's range map uses the raw prop, so the UI can disagree with what mounts

useLazyPages computes the window as Math.max(preloadDistance, 0) + 1 (useLazyPages.tsx:27) and the hook itself takes no lower/upper validation of the prop: PagerViewProps.lazyPreloadDistance is a plain number with a default of 1 (PagerView.tsx:45,92). A caller passing a negative value gets distance = 1 (current page only, i.e. silently the same as 0) rather than an error, and a caller passing a fractional value such as 1.5 gets a window of 2 (an asymmetric, silently-rounded range). The public prop is documented in README.md:103 as "how many pages on each side … Defaults to 1", which neither of those behaviours matches. There is no validation or rounding at the prop boundary — the coercion is buried inside the +1 expression, so the documented semantics and the implemented window can diverge for any value that is not a non-negative integer.

Suggested change

Normalise lazyPreloadDistance once at the public boundary (Math.max(0, Math.round(n))) so the documented "pages on each side" matches the implemented window for negative and fractional inputs, and say so in the prop JSDoc.

Reply @apex-sentinel-staging note ... to add context, or @apex-sentinel-staging pivot ... if this is wrong — I will re-check the cited code.

Useful? Reply @apex-sentinel-staging like, or @apex-sentinel-staging dislike <why> if it is not.

No longer raised on b0040e6.

🆕 🔵 Nit · Placeholder <View> reuses the page's key, so React can reuse the instance when the page mounts

useLazyPages returns a fresh children array on every PagerView render, and for the default non-lazy path that array is props.children itself. That array identity is now what childrenWithOverriddenStyle (src/utils.tsx:8, src/utils.ios.tsx:8) iterates with Children.map, and the result feeds the native children prop of RNCViewPager. Two consequences:

Suggested change

Give the placeholder a key distinct from the page's key (or a non-View wrapper type) so React cannot reuse the placeholder instance as the mounted page.

Reply @apex-sentinel-staging note ... to add context, or @apex-sentinel-staging pivot ... if this is wrong — I will re-check the cited code.

Useful? Reply @apex-sentinel-staging like, or @apex-sentinel-staging dislike <why> if it is not.

No longer raised on b0040e6.

🆕 🔵 Nit · renderLazyPlaceholder returns content for a page index, but that content is wrapped in a plain View whose only style is the page margin

For an unmounted page the hook returns <View key={...}>{renderPlaceholder?.(index)}</View>, and childrenWithOverriddenStyle then overwrites that View's style with { marginHorizontal: pageMargin } (src/utils.tsx:47) — no flex: 1. The README example (renderLazyPlaceholder={() => <View style={{flex: 1, justifyContent: 'center'}}><ActivityIndicator /></View>}) only fills the pager because the outer wrapper never stretches, so with pageMargin set the placeholder is additionally shifted sideways and vertically centered over a zero-flex container, which can read as an empty page. Documented behavior ("what a page shows before its content is mounted") therefore depends on the consumer adding a style the wrapper cannot carry. Either give the wrapper {flex: 1} and merge rather than overwrite in childrenWithOverriddenStyle, or say in the renderLazyPlaceholder jsdoc that the returned node is wrapped in a flex-less View.

Suggested change

Make the placeholder wrapper flex: 1 (or merge styles instead of overwriting them in childrenWithOverriddenStyle) so a placeholder that uses flex: 1 actually fills the page, and note the wrapper in the prop's doc comment.

Reply @apex-sentinel-staging note ... to add context, or @apex-sentinel-staging pivot ... if this is wrong — I will re-check the cited code.

Useful? Reply @apex-sentinel-staging like, or @apex-sentinel-staging dislike <why> if it is not.

🟡 Minor · setPage out of range sets lazy current, leaving the pager showing placeholders over an unmoved page

setPage(100) on a 20-page pager sets lazy current to 100, causing every real page to render as a placeholder permanently because native never fires a corrective onPageSelected—the page never moved. The requested position is passed to setCurrent before validation, and mountNear in useLazyPages clamps only preloadDistance, never the page index against the child count. Clamp in useLazyPages (bounds known there from pages.length) or only adopt a position the native pager can actually select.

Reply @apex-sentinel-staging note ... to add context, or @apex-sentinel-staging pivot ... if this is wrong — I will re-check the cited code.

Useful? Reply @apex-sentinel-staging like, or @apex-sentinel-staging dislike <why> if it is not.

🟡 Minor · Animated.event handlers are now wrapped in plain JS closures, forcing per-frame JS on every caller

A caller passing onPageScroll={Animated.event(..., { useNativeDriver: true })} with no listener now pays per-frame JS dispatch, because PagerView always installs its own onPageScroll/onPageSelected props, wrapping the caller's handler in a plain function. The native-driver short-circuit only fires when the registered prop is an AnimatedEvent object directly, so the wrapper forces every scroll frame through JS for all existing callers.

Reply @apex-sentinel-staging note ... to add context, or @apex-sentinel-staging pivot ... if this is wrong — I will re-check the cited code.

Useful? Reply @apex-sentinel-staging like, or @apex-sentinel-staging dislike <why> if it is not.